Stardog supports all of the functions in SPARQL, as well as some others from XPath and SWRL. Any of these functions can be used in queries or rules. Some functions appear in multiple namespaces, but all of the namespaces will work:

The function names and URIs supported by Stardog are included below. Some of these functions exist in SPARQL natively, which just means they can be used without an explicit namespace.

SPARQL’s DESCRIBE keyword is deliberately underspecified; vendors are free to do, for good or bad, whatever they want. In Stardog a DESCRIBE <theResource> query retrieves the predicates and objects for all the triples for which <theResource> is the subject. There are, of course, about seventeen thousand other ways to implement DESCRIBE; we’ve implemented four or five of them and may expose them to users in a future release of Stardog based on user feedback and requests.

Now you know and knowing is one-quarter of the fun.

SPARQL 1.1 Update can be used to insert RDF into or delete RDF from a Stardog database using SPARQL query forms INSERT and DELETE, respectively.

An example of deleting RDF:

Or they can be combined with WHERE clauses:

The most efficient way to load data into Stardog is at database creation time. See the [Creating a Database](../admin/#create) section for bulk loading data at database creation time. To add data to an existing Stardog database, use the [add](/docs/man/data-add.html) command:

The optional arguments are -f (or --format) to specify the RDF serialization type of the files to be loaded; if you specify the wrong type, add will fail. If you don’t specify a type, Stardog will try to determine the type on its own based on the file extension. For example, the files that have names ending with '.ttl' will be parsed with Turtle syntax. If you specify a type, then all the files being loaded must of that same type.

If you want to add data to a named graph, specify it via the --graph-uri or -g options.

To remove data from a Stardog database, remove is used by specifying

For example,

will remove the named graph http://foo and all its triples from myDatabase.

will remove the triples in 1.rdf from (the default graph of) myDatabase.

will remove the triples in the Turtle files 2.rdf and 3.rdf from the named graph http://foo of myDatabase.

Strict or loose parsing may be set for the input payload by using --strict-parsing=TRUE|FALSE.

RDF parsing in Stardog is strict: it requires typed RDF literals to match their explicit datatypes, URIs to be well-formed, etc. In some cases, strict parsing isn’t ideal—it may be disabled using the --strict-parsing=FALSE.

However, even with strict parsing disabled, Stardog’s RDF parser may encounter parse errors from which it cannot recover. And loading data in lax mode may lead to unexpected SPARQL query results. For example, malformed literals ("2.5"^^xsd:int) used in filter evaluation may lead to undesired results.

Commit a new version by adding and removing triples specified in files. Different from the data add/remove commands, commit allows one to add and remove triples in one commit and to associate a commit message.

To commit changes:

To see all revisions (commits) in a database:

The output can be tweaked using --after, --before, and --committer.

You can revert specific revisions, ranges, etc.

You can also see the differences between revisions; by default, between the head version and its previous versions or the changes in a specific commit, respectively:

You can also create, drop, list tags, i.e., named revisions:

The revision history of the database is represented as RDF using the W3C PROV vocabulary and can be queried using SPARQL:[6]

The indexing strategy creates a "search document" per RDF literal. Each document consists of the following fields: literal ID; literal value; and contexts.

We use the predicate http://jena.hpl.hp.com/ARQ/property#textMatch to access the search index in a SPARQL query.

For example,

This query selects the top 50 literals, and their scores, which match 'mac' and whose scores are above a threshold of 0.5. These literals are then joined with the generic BGP ?s ?p ?l to get the resources (?s) that have those literals. Alternatively, you could use ?s rdf:type ex:Book if you only wanted to select the books which reference the search criteria; you can include as many other BGPs as you like to enhance your initial search results.

First, check out the search man page:

Okay, now let’s do a search over the O’Reilly book catalog in RDF for everything mentioning "html":

The results?

Stardog search is based on Lucene 4.2.0: we support all of the search modifiers that Lucene supports, with the exception of fields.

For a more detailed discussion, see the Lucene docs.

Seriously, this is a lot more fun if you just [download](http://stardog.com/) the damn thing and hit it with a browser!

To use the Stardog CLI tools, you can start by asking them to display help:

Or:

And for the very laziest among us, these work too:

We split administrative functionality into two CLI programs because of security: stardog-admin will need, in production environments, to have considerably tighter access restrictions than stardog.

The CLI tools use "command groups" to make CLI subcommands easier to find. To print help for a particular command group, just ask for help:

The command groups and their subcommands include

The main help command for either CLI tool will print a listing of the command groups:

To get more information about a particular command, simply issue the help command for it including its command group:

Finally, everything here about command groups, commands, and online help works for stardog-admin, too. The result of all these changes is a better user experience:

Stardog also supports CLI autocomplete via bash autocompletion. To install autocomplete for bash shell, you’ll first want to make sure bash completion is installed:

You need to make a connection string to talk to a Stardog database.

A connection string may consist solely of the database name in cases where

In other cases, a "fully qualified" connection string, as described below, is required.

Further, the connection string is now assumed to be the first argument of any command that requires a connection string. Some CLI subcommands require a Stardog connection string as an argument to identify the server and database upon which operations are to be performed.

Connection strings are URLs and may either be local to the machine where the CLI is run or they may be on some other remote machine.

There are two URL schemes recognized by Stardog:

The former uses Stardog’s (extended) version of SPARQL Protocol; the latter uses Stardog’s native data access protocol, called SNARL.

To make a connection string, you need to know the URL scheme; the machine name and port Stardog Server is running on; any (optional) URL path to the database;[7] and the name of the database:

For example,

Using the default ports for SNARL and HTTP protocols simplifies connection strings. connectionOptions are a series of ; delimited key-value pairs which themselves are = delimited. Key names must be lowercase and their values are case-sensitive. Finally, in the case where the scheme is SNARL, the machine is "localhost", and the port is the default SNARL port, a connection string may consist of the "databaseName" only.

The process of installation is pretty simple; see the Quick Start Guide for details.

But how do we easily upgrade between versions? The key is judicious use of STARDOG_HOME. Best practice is to keep installation directories for different versions separate and use a STARDOG_HOME in another location for storing databases.[8] One you set your STARDOG_HOME environment variable to point to this directory, you can simply stop the old version and start the new version without copying or moving any files. You can also specify the home directory using the --home` argument when starting the server.

To use any of these commands against a remote server, pass a global --server argument with an HTTP or SNARL URL.

See the Security section for information about Stardog’s security system, secure deployment patterns, and more.

Stardog Server’s behavior can be configured via the JVM arg stardog.home, which sets Stardog Home, overriding the value of STARDOG_HOME set as an environment variable. Stardog Server’s behavior can also be configured via a stardog.properties—which is a Java Properties file—file in STARDOG_HOME. To change the behavior of a running Stardog Server, it is necessary to restart it.

The following twiddly knobs for Stardog Server are available in stardog.properties:[9]

The simplest way to start the server—running on the default port, detaching to run as a daemon, and writing stardog.log to the current working directory— is

To specify parameters:

The port can be specified using the property --port. The HTTP interface can be disabled by using the flag --no-http and the SNARL interface via --no-snarl.

To shut the server down:

If you started Stardog on a port other than the default, or want to shut down a remote server, you can simply use the --server option to specify the location of the server to shutdown.

By default Stardog will bind it’s server to 0.0.0.0. You can specify a different network interface for Stardog to bind to using the --bind property of server start.

Stardog’s JMX implementation is called Watchdog. In addition to providing some basic JVM information, Watchdog also exports information about the Stardog DBMS configuration as well as stats for all of the databases within the system, such as the total number of open connections, size, and average query time.

Stardog Server will lock STARDOG_HOME when it starts to prevent synchronization errors and other nasties if you start more than one Stardog Server with the same STARDOG_HOME. If you need to run more than one Stardog Server instance, choose a different STARDOG_HOME or pass a different value to --home.

See the stardog.properties file (in the distribution) for a complete discussion of how access and audit logging work in Stardog Server. Basically, audit logging is a superset of the events in access logging. Access logging covers the most often required logging events; you should consider enabling audit logging if you really need to log every server event. Logging generally doesn’t have much impact on performance; but the safest way to insure that impact is negligible is to log to a separate disk (or to a centralized logging server, etc.).

The important configuration choices are whether logs should be binary or plain text (both based on ProtocolBuffer message formats); the type of logging (audit or access); the logging location (which may be "off disk" or even "off machine") Logging to a centralized logging facility requires a Java plugin that implements the Stardog Server logging interface; see the [Java Chapter](/java/) for more information; and the log rotation policy (file size or time).

Slow query logging is also available. See the Managing Queries section below.

To administer a Stardog database, some config options must be set at creation time; others may be changed subsequently and some may never be changed. All of the config options have sensible defaults (except, obviously, for the database name), so you don’t have to twiddle any of the knobs till you really need to.

The following are the legal configuration options for a Stardog database:

Databases are either online or offline; this allows database maintenance to be decoupled from server maintenance.

Stardog databases may be created locally or remotely; but, of course, performance is better if data files don’t have to be transferred over a network during creation and initial loading. See the section below about loading compressed data. All data files, indexes, and server metadata for the new database will be stored in Stardog Home. Stardog won’t create a database with the same name as an existing database. Stardog database names must conform to the regular expression, [A-Za-z]{1}[A-Za-z0-9_-].

Minimally, the only thing you must know to create a Stardog database is a database name; alternately, you may customize some other database parameters and options depending on anticipated workloads, data modeling, and other factors.

See stardog-admin help db create for all the details including examples.

Stardog database archetypes are a new feature in 2.0. A database archetype is a named, vendor-defined or user-defined bundle of data and functionality to be applied at database-creation time. Archetypes are primarily for supporting various data standards or toolchain configurations in a simple way.

For example, the SKOS standard from W3C defines an OWL vocabulary for building taxonomies, thesauruses, etc. SKOS is made up by a vocabulary, some constraints, some kinds of reasoning, and (typically) some SPARQL queries. If you are developing an app that uses SKOS, without Stardog’s SKOS archetype, you are responsible for assembling all that SKOS stuff yourself. Which is tedious, error-prone, and not very rewarding—​even when it’s done right the first time.

Rather than putting that burden on Stardog users, we’ve created database archetypes as a mechanism to collect these "bundles of stuff" which, as a developer, you can then simply attach to a particular database.

The last point to make is that archetypes are composable: you can mix-and-match them at database creation time as needed.

Stardog supports two database archetypes out-of-the-box: PROV and SKOS.

As a boon to the overworked admin or devops peeps, Stardog Server supports database creation templates: you can pass a Java Properties file with config values set and with the values (typically just the database name) that are unique to a specific database passed in CLI parameters.

If an I/O error or an index exception occurs while querying a DB, the DB might be corrupted and repaired with the repair command. If the errors occur during executing admin commands, then the system DB might have been corrupted. System database corruptions can also cause other problems including authorization errors.

This command needs exclusive access to your Stardog home directory and therefore requires the Stardog Server not to be running. This also means that the command can only be run on the machine where the Stardog home directory is located, and you will not be able to start the Stardog Server while this command is running.

If the built-in Stardog system database is corrupted, then you can use the database name system as the repair argument. To repair the database myDB:

To repair the system database:

Stardog includes both physical and logical backup utilities; logical backups are accomplished using the export CLI command. Physical backups and restores are accomplished using stardog-admin db backup and stardog-admin db restore commands, respectively.

These tools perform physical backups, including database metadata, rather than logical backups via some RDF serialization. They are native Stardog backups and can only be restored with Stardog tools. Backup may be accomplished while a database is online; backup is performed in a read transaction: reads and writes may continue, but writes performed during the backup are not reflected in the backup.

See the man pages for backup and restore for details.

SPARQL queries can be verbose; but at least the PREFIX declarations in the prologue of each query are easy to screw up! Stardog allows database administrators to persist and manage custom namespace prefix bindings:

If no files are used during database creation, or if the files do not define any prefixes (e.g. NTriples), then the "Big Four" default prefixes are stored: RDF, RDFS, XSD, and OWL.

When executing queries in the CLI, the default table format for SPARQL SELECT results will use the bindings as qnames. SPARQL CONSTRUCT query output (including export) will also use the stored prefixes. To reiterate, namespace prefix bindings are per database, not global.

By default Stardog builds extra indexes for named graphs. These additional indexes are used when SPARQL queries specify datasets using FROM and FROM NAMED. With these additional indexes, better statistics about named graphs are also computed.

Stardog may also be configured to create and to use fewer indexes, if the database is only going to be used to store RDF triples—​that is to say, if the database will not be used to store named graph information. In this mode, Stardog will maintain fewer indexes, which will result in faster database creation and faster updates without compromising query answering performance. In such databases, quads (that is: triples with named graphs or contexts specified) may still be added to these database at any time, but query performance may degrade in such cases.

To create a database which indexes only RDF triples, set the option index.named.graphs to false at database creation time. The CLI provides a shorthand option, -i or --index-triples-only, which is equivalent.

While Stardog is generally biased in favor of read performance, write performance is also important in many applications. In order to increase write performance, Stardog may be used, optionally, with a differential index.

Stardog’s differential index is used to persist additions and removals separately from the main indexes, such that updates to the database can be performed faster. Query answering takes into consideration all the data stored in the main indexes and the differential index; hence, query answers are computed as if all the data is stored in the main indexes.

There is a slight overhead for query answering with differential indexes if the differential index size gets too large. For this reason, the differential index is merged into the main indexes when its size reaches DIFF_INDEX_MAX_LIMIT. There is no benefit of differential indexes if the main index itself is small. For this reason, the differential index is not used until the main index size reaches DIFF_INDEX_MAX_LIMIT.

In most cases, the default value of the DIFF_INDEX_MAX_LIMIT parameter will work fine and doesn’t need to be changed. The corollary is that you shouldn’t change this value in a production system till you’ve tested the effects of a change in a non-production system.

Stardog supports loading data from compressed files directly: there’s no need to uncompress files before loading. Loading compressed data is the recommended way to load large input files. Stardog supports GZIP and ZIP compressions natively.[10]

This command removes a database and all associated files and metadata. This means all files on disk pertaining to the database will be deleted, so only use drop when you’re certain! Databases must be offline in order to be dropped.

It takes as its only argument a valid database name. For example,

Stardog supports integrity constraint validation as a data quality mechanism via closed world reasoning. Constraints can be specified in OWL, SWRL, and SPARQL. Please see the Integrity Constraint Validation section for more about using ICV in Stardog.

The CLI icv subcommand can be used to add, delete, or drop all constraints from an existing database. It may also be used to validate an existing database with constraints that are passed into the icv subcommand; that is, using different constraints than the ones already associated with the database.

For details of ICV usage, see stardog help icv and stardog-admin help icv. For ICV in transacted mutations of Stardog databases, see the database creation section above.

The migrate subcommand migrates an older Stardog database to the latest version of Stardog. Its only argument is the name of the database to migrate. migrate won’t necessarily work between arbitrary Stardog version, so before upgrading check the release notes for a new version carefully to see whether migration is required or possible.

will update myDatabase to the latest database format.

You can get some information about a database by running the following command:

This will return all the metadata stored about the database, including the values of configuration options used for this database instance. If you want to get the value for a specific option then you can run the following command:

Stardog includes the capability to manage running queries according to configurable policies set at run-time; this capability includes support for listing running queries; deleting running queries; reading the status of a running query; killing running queries that exceed a time threshold automatically; and logging slow queries for analysis.

Stardog is pre-configured with sensible server-wide defaults for query management parameters; these defaults may be overridden or disabled per database.

Stardog’s search service is described in Using Stardog section. However, managing search indexes is an administrative task and, thus, is described here.

There are three modes for rebuilding indexes:

This is specified when creating a database by setting the property search.reindex.mode to sync, async, or to a valid cron expression. The default is sync.

Stardog tries hard to do bulk loading at database creation time in the most efficient and scalable way possible. But data loading time can vary widely, depending on factors in the data to be loaded, including the number of unique resources, etc. Here are some tuning tips that may work for you:

Stardog uses system memory aggressively and the total system memory available to Stardog is often the most important factor in performance. Stardog uses both JVM memory (heap memory) and also the operating system memory outside the JVM (off heap memory). Having more system memory available is always good; however, increasing JVM memory too close to total system memory is not usually prudent as it may tend to increase Garbage Collection (GC) time in the JVM.

The following table shows recommended JVM memory and system memory requirements for Stardog.[15]

By default, Stardog CLI sets the maximum JVM memory to 2GB. This setting works fine for most small databases (up to, say, 100 million triples). As the database size increases, we recommend increasing JVM memory. You can increase the JVM memory for Stardog by setting the system property STARDOG_JAVA_ARGS using the standard JVM options. For example, you can set this property to "-Xms4g -Xmx4g -XX:MaxDirectMemorySize=8g" to increase the JVM memory to 4GB and off-heap to 8GB. We recommend setting the minimum heap size (-Xms option) as close to the max heap size (-Xmx option) as possible.

Stardog stores data on disk in a compressed format. The disk space needed for a database depends on many factors besides the number of triples, including the number of unique resources and literals in the data, average length of resource identifiers and literals, and how much the data is compressed. The following table shows typical disk space used by a Stardog database.

These numbers are given for information purposes only; the actual disk usage for a database may be significantly different in practice. Also it is important to note that the amount of disk space needed at creation time for bulk loading data is higher as temporary files will be created. The additional disk space needed at bulk loading time can be 40% to 70% of the final database size.

Disk space used by a database is non-trivially smaller if triples-only indexing is used. Triples-only indexing reduces overall disk space used by 25% on average; however, note the tradeoff: SPARQL queries involving named graphs perform significantly better with quads indexing.

The disk space used by Stardog is additive for multiple databases and there is very little disk space used other than what is required for the databases. To calculate the total disk space needed for multiple databases, one may sum the disk space needed by each database.

You can run Stardog as a Windows Service using the following configuration. Please, note, that the following assumes commands are executed from a Command Prompt with administrative privileges.

Requirement: Oracle VirtualBox v4.2.x if deploying to VirtualBox servers

Before deploying Stardog Cluster image nodes to VirtualBox—​we refer to this provider as vmfest--make sure to follow these steps.

Open a terminal and start VirtualBox’s webservice:

In a new terminal add the identities stored in your public ssh key:

OS X:

Linux:

Adding your public key to the ssh agent allows interacting with the vitual machine, and also lets you log in to the virtual machine using ssh <ip address>.

Requirements: An EC2 account on Amazon Web Services for EC2 deployments, along with your key pair and Access ID and Secret Key.

Make sure to have a key pair and add it via the ssh agent using:

OS X:

Linux:

Adding your public key to the ssh agent allows interacting with the remote machine, and also lets you log in to the virtual machine using ssh <ip address>.

Make sure to have an Access Key ID and a Secret Access Key and then add them to your configuration file located in ~/.starmanconfig:

Optionally, specify the instance type. Starman by default creates m1.medium EC2 instances, but you can specify in .starmanconfig` some other EC2 instance types:

Note that the only instance types allowed are the ones in the AWS SDK. Compare those values with the most current EC2 instance types for more info.

In order to simplify the process we assume that the remote machines are running Ubuntu, and that the user has password-less SSH access and is able to execute password-less sudo in the remote machines.

As of Stardog 2.2.1, the only cluster commands supported for deploying to existing servers are cluster deploy, cluster start and cluster stop. Before using Starman with existing servers, you will need to edit the Starman configuration file located in ~/.starmanconfig and make sure to add the list of default nodes as follows:

where the property default-nodes is a colon-separated list of IP addresses that correspond to the existing servers.

To add nodes to an existing cluster:

It will add num_vms to a cluster. Please note that if a node is added to a cluster, it will only start a Stardog server in the new nodes; if you want to also replicate the ZooKeeper servers, you will have to stop the cluster and start it again. This limitation is due to the fact that ZooKeeper is not capable of hot reconfiguration as of v3.4.x.

To remove nodes from an existing cluster there are two options:

It will remove num_vms from a cluster. Note that this will remove an entire VM from the cluster, which may or not also remove a ZooKeeper server. ZooKeeper is able to account for node failures, but this may not be the behavior the user intended. The other option is to specify a comma-separated list of IP addresses that correspond to the IPs of nodes to be removed:

We can verify that Stardog Cluster was deployed successfully using

You should see a list of the created nodes. Since Starman adds a password-less login with SSH authentication on the remote machines, you can also log in via SSH:

In order to undeploy a Cluster:

This will destroy all the virtual or remote machines part of cluster.

If you wish to uninstall a Stardog Cluster image from your local Starman system use:

If you wish to remove a Stardog Cluster image tag from your local Starman system use:

To list bootstrapped and installed Stardog Pack versions:

To add or remove data, simply use the stardog data add or remove commands to any node in the cluster. Queries can be issued to any node in the cluster using the stardog query command. All the stardog-admin features are also available in cluster mode, which means you can use any of the commands to create databases, adminster users, and the rest of the functionality available in single server mode.

You can use Starman to copy files remotely for bulk loading files to your cluster:

<origin> is the path in your local machine and <destination> is the path in the remote machines. This command will copy the local files to all the servers in the cluster in the specified path.

When a client commits a transaction (containing a list of write requests), it will be acknowledged by the Coordinator only after every non-failing Participant has committed the transaction. If a Participant fails during the process of committing a transaction, it will be expelled from the cluster by the Coordinator and put in a temporary failed state.

If the Coordinator fails during the process, the transaction will be aborted, and a new Coordinator will be elected automatically. Since failed nodes are not used for any subsequent read or write requests, if a commit is acknowledged by the Coordinator, then Stardog Cluster guarantees that the data has been accordingly modified at every available node in the cluster.

While this approach is less performant with respect to write operations than eventual consistency used by other distributed databases, typically those databases offer a much less expressive data model than Stardog, which makes an eventually consistency model more appropriate for those systems. But since Stardog’s data model is not only richly expressive but rests in part on provably correct semantics, we think that a strong consistency model is worth the cost.[19]

Stardog understands the use of wildcards to represent sets of resources. A wildcard is denoted with the character *. Wildcards can be used to create complex permissions; for instance, we can give a user the ability to create any database by granting it a create permission over db:*. Similarly, wildcards can be used in order to revoke multiple permissions simultaneously.

It is possible at (user) creation time to specify that a given user is a superuser. Being a superuser is equivalent to having been granted an all permission over *:*. Therefore, as expected, superusers are allowed to perform any valid action over any existing resource.

When a user creates a resource, it is automatically granted delete, write, read, grant, and revoke permissions over the new resource. If the new resource is a database, then the user is additionally granted write, read, grant, and revoke permissions over icv-constraints:theDatabase and execute permission over admin:theDatabase. These latter two permissions give the creator of the database the ability to administer the ICV constraints for the database and to administer the database itself.

Do not deploy Stardog in production or hostile environments with the default security settings.

To setup the constraints used to validate passwords when adding new users, configure the following settings in the stardog.properties configuration file.

To avoid putting passwords into scripts or environment variables, you can put them into a suitably secured password file. If no credentials are passed explicitly in CLI invocations, or you do not ask Stardog to prompt you for credentials interactively, then it will look for credentials in a password file. On a Unix system, Stardog will look for a file called .sdpass in the home directory of the user Stardog is running as; on a Windows system, it will look for sdpass.conf in Application Data\stardog in the home directory of the user Stardog is running as. If the file is not found in this location, Stardog will look in the location provided by the stardog.passwd.file system property.

StardogHTTP server includes native support for SSL. The SNARL server (via snarls://) also supports SSL. Stardog may also be deployed securely using two other methods:

However, in most cases, it’s just easier to use Stardog’s native SSL support.

To enable Stardog to optionally support SSL connections, just pass --enable-ssl to the server start command. If you want to require the server to use SSL only, that is, to reject any non-SSL connections, then use --require-ssl.

When starting from the command line, Stardog will use the standard Java properties for specifying keystore information:

These properties are checked first in stardog.properties; then in JVM args passed in from the command line, e.g. -Djavax.net.ssl.keyStorePassword=mypwd. If you’re creating a Server progammatically via ServerBuilder, you can specify values for these properties using the appropriate ServerOptions when creating the server. These values will override anything specified in stardog.properties or via normal JVM args.

Stardog HTTP client supports SSL when the https: scheme is used in the database connection string; likewise, it uses SSL for SNARL when the connection string uses the snarls: scheme. For example, the following invocation of the Stardog command line utility will initiate an SSL connection to a remote database:

If the client is unable to authenticate to the server, then the connection will fail and an error message like the following will be generated.

The most common cause of this error is that the server presented a certificate that was not issued by an authority that the client trusts. The Stardog HTTP client driver uses standard Java security components to access a store of trusted certificates. By default, it trusts a list of certificates installed with the Java runtime environment, but it can be configured to use a custom trust store.[26]

The client driver can be directed to use a specific Java KeyStore file as a trust store by setting the javax.net.ssl.trustStore system property. To address the authentication error above, that trust store should contain the issuer of the server’s certificate. Standard Java tools can create such a file. The following invocation of the keytool utility creates a new trust store named my-truststore.jks and initializes it with the certificate in my-trusted-server.crt. The tool will prompt for a passphrase to associate with the trust store. This is not used to encrypt its contents, but can be used to ensure its integrity.[27]

The following Stardog command line invocation uses the newly created truststore.

For custom Java applications that use the Stardog HTTP client driver, the system property can be set programmatically or when the JVM is initialized.

The most common deployment approach requiring a custom trust store is when a self-signed certificate is presented by the Stardog server. For connections to succeed, the Stardog client must trust the self-signed certificate. To accomplish this with the examples given above, the self-signed certificate should be in the my-trusted-server.crt file in the keytool invocation.

A client may also fail to authenticate to the server if the hostname in the Stardog database connection string does not match a name contained in the server certificate.[28]

This will cause an error message like the following

The client driver does not support connecting when there’s a mismatch; therefore, the only workarounds are to replace the server’s certificate or modify the connection string to use an alias for the same server that matches the certificate.

The Stardog library files should be copied from the distribution directory into a permanent location in the host system—​we’re big fans of the /opt--and--/var approach, but your needs may vary. The snippet below chooses a common location and uses a versioning string to facilitate parallel installs of different Stardog releases. An administrator may choose any location.

The Stardog command line tools should be copied from the distribution directory into a location that places them into most users’ execution PATH. Execution permissions to the tools are not limited because access to the data directory will be strictly limited.

The Stardog data directory stores both user data and system configuration data, including access control information. The location selected for the data directory should be reliable, large enough to meet data requirements, and secured from unauthorized access.

Access to the data directory is limited to the stardog group and the only member of that group is the stardog user. Granting access permissions to members of the stardog group is more flexible than limiting access to a single user. For example, it may allow a Stardog network server to run as a user other than stardog; or it may facilitate other processes other than Stardog, i.e., data backup. The snippet below creates that user and group.

This snippet creates the data directory and limits its access to the newly created group.

Note that if a Stardog server is used to allow network access to remote Stardog clients, then the approach described here requires the server to run as a user in the stardog group.

An administrator can accomplish this by running the server as the stardog user or by adding the relevant user to the stardog group. For example, the following snippet adding the tomcat user to the stardog group may be needed in an environment where a Stardog HTTP server is run as an application within Tomcat.

Of course the ideal deployment of the Stardog server depends on the particulars of the deployment environment, the preferences of the administrator, and the anticipated user load. The group-based permission approach provides flexibility to satisfy many alternatives.

All of Stardog’s interfaces (API, network, and CLI) support reasoning during query evaluation.

In order to evaluate queries in Stardog using reasoning via the command line, a specific reasoning level must be specified in the connection string:

For HTTP, the reasoning level is specified with the other HTTP request parameters:

In order to use the ReasoningConnection API one needs to specify a reasoning level. See the Java Programming section for details on specifying the reasoning level programmatically.

Currently, the API has two methods:

Proof trees are a hierarchical presentation of multiple explanations (of inferences) to make data, schemas, and rules more intelligible. Proof trees[32] provide an explanation for an inference or an inconsistency as a hierarchical structure. Nodes in the proof tree may represent an assertion in a Stardog database. Multiple assertion nodes are grouped under an inferred node.

Stardog supports two different syntaxes for defining rules. The first is native Stardog Rules syntax and is based on SPARQL, so you can re-use what you already know about SPARQL to write rules. Unless you have specific requirements otherwise, you should use this syntax for user-defined rules in Stardog. The second is the de facto standard RDF/XML syntax for SWRL. It has the advantage of being supported in many tools; but it’s not fun to read or to write. You probably don’t want to use it. Better: don’t use this syntax!

Stardog Rules Syntax is basically SPARQL "basic graph patterns" (BGPs) plus some very explicit new bits (IF-THEN) to denote the head and the body of a rule.[33] You define URI prefixes in the normal way (examples below) and use regular SPARQL variables for rule variables. As you can see, some SPARQL 1.1 syntactic sugar—​property paths, especially, but also bnode syntax—​make complex Stardog Rules concise and elegant.

Stardog supports a wide variety of functions from SPARQL, XPath, SWRL, and some native Stardog functions, too. All of them may be used in either Stardog Rules syntax or in SWRL syntax. The supported functions are enumerated here.

Besides the standard RDF(S) predicates rdf:type, rdfs:subClassOf and rdfs:subPropertyOf, Stardog supports the following special built-in predicates:

Where the sp prefix binds to tag:stardog:api:property:. Stardog also recognizes sesame:directType, sesame:directSubClassOf, and sesame:strictSubClassOf predicates where the prefix sesame binds to http://www.openrdf.org/schema/sesame#.

We show what these each of these predicates means by relating them to an equivalent triple pattern; that is, you can just write the predicate rather than the (more unwieldy) triple pattern.

The predicates sp:directSubPropertyOf and sp:strictSubPropertyOf are defined analogously.

Stardog also supports a special predicate that extends the expressivity of SWRL rules. According to SWRL, you can’t create new individuals (i.e., new instances of classes) in a SWRL rule.

This restriction is well-motivated; without it, you can easily create rules that do not terminate, that is, never reach a fixed point. Stardog’s user-defined rules weakens this restriction in some crucial aspects, subject to the following restrictions, conditions, and warnings.

So despite the general restriction in SWRL, in Stardog we actually can create new individuals with a rule by using the function UUID() as follows:

This rule will create a random URI for each instance of the class :Parent and also assert that each new instance is an instance of :Person--parents are people, too!

Query rewriting has several advantages over materialization. In materialization, the data gets expanded with respect to the schema, not with respect to any actual query. And it’s the data—​all of the data—​that gets expanded, whether any actual query subsequently requires reasoning or not. The schema is used to generate new triples, typicaly when data is added or removed from the system. However, materialization introduces several thorny issues:

When a SPARQL query gets executed, each variable is bound to a URI, blank node, or to a literal to form a particular result (a collection of these results is a result set). In the context of reasoning, URIs might represent different entities: individuals, classes, properties, etc. According to the relevant standard, every variable in a SPARQL query must bind to at most one of these types of entity.

Stardog can often figure out the right entity type from the query itself (e.g., given the triple pattern ?i ?p "a literal", we know ?p is supposed to bind to a data property); however, sometimes this isn’t possible (e.g., ?s ?p ?o). In case the types can’t be determined automatically, Stardog logs a message and evaluates the query without any reasoning.

You can add one or more type triples to the query to resolve these ambiguities.[35]

These "type triples" have the form ?var a TYPE, where TYPE is a URI representing the type of entity to which the variable ?var is supposed to bind: the most common are owl:ObjectProperty or owl:DatatypeProperty; in some cases, you might want owl:NamedIndividual, or owl:Class. For instance, if you are interested in all the object properties of :i1, you can use the following query:

Since Stardog now knows that ?p should bind to an object property, we can now infer that ?o binds to an individual, so there are no ambiguities and reasoning can be performed as requested.

Stardog might be extracting the wrong schema. You have to tell Stardog where to find the schema. See database configuration options for details.

Perhaps some of the modeling constructs (a.k.a. axioms) in your database are being ignored. You can find out which axioms are being ignored by including the following line in the logging.properties file in STARDOG_HOME:

Stardog supports schema-only reasoning for OWL 2 DL, which effectively means that only TBox queries—queries that contain TBox BGPs only—will return complete query results.

As from version 2.0, SWRL rules are only taken into account using the SL reasoning level.

The OWL 2 primer is a good place to start.

A database (DB), a.k.a. ontology, is composed of two different parts: the schema or Terminological Box (TBox) and the data or Assertional Box (ABox). Analogus to relational databases, the TBox can be thought of as the schema, and the ABox as the data. In other words, the TBox is a set of axioms, whereas the ABox is a set of assertions.

As we explain in OWL 2 Profiles, the kinds of assertion and axiom that one might use for a particular database are determined by the fragment of OWL 2 to which you’d like to adhere. In general, you should choose the OWL 2 profile that most closely fits the data modeling needs of your application.

The most common data assertions are class and property assertions. Class assertions are used to state that a particular individual is an instance of a given class. Property assertions are used to state that two particular individuals (or an individual and a literal) are related via a given property. For example, suppose we have a DB MyDB₂ that contains the following data assertions. We use the usual standard prefixes for RDF(S) and OWL.

Which says that :clark_and_parsia is a company, and that :clark_and_parsia maintains :Stardog.

The most common schema axioms are subclass axioms. Subclass axioms are used to state that every instance of a particular class is also an instance of another class. For example, suppose that MyDB₂ contains the following TBox axiom:

stating that companies are a type of organization.

When reasoning is enabled, Stardog executes SPARQL queries depending on the type of Basic Graph Patterns they contain. A BGP is said to be an "ABox BGP" if it is of one of the following forms:

A BGP is said to be a TBox BGP if it is of one of the following forms:

A BGP is said to be a Hybrid BGP if it is of one of the following forms:

where term (possibly with subscripts) is either an URI or variable; uri is a URI; and ?var is a variable.

When executing a query, ABox BGPs are handled by Stardog. TBox BGPs are executed by Pellet embedded in Stardog. Hybrid BGPs by a combination of both.

Intuitively, reasoning with a DB means to make implicit knowledge explicit. There are two main use cases for reasoning: to infer implicit knowledge and to discover modeling errors.

With respect to the first use case, recall that MyDB₂ contains the following assertion and axiom:

From this DB, we can use Stardog in order to infer that :clark_and_parsia is an organization:

Using reasoning in order to infer implicit knowledge in the context of an enterprise application can lead to simpler queries. Let us suppose, for example, that MyDB₂ contains a complex class hierarchy including several types of organization (including company). Let us further suppose that our application requires to use Stardog in order to get the list of all considered organizations. If Stardog were used with reasoning, then we would need only issue the following simple query:

In contrast, if we were using Stardog with no reasoning, then we would have to issue a more complex query that considers all possible types of organization, thus coupling queries to domain knowledge in a tight way:

Which of these queries seems more loosely coupled and more resilient to change?

Stardog can also be used in order to discover modeling errors in a DB. The most common modeling errors are unsatisfiable classes and inconsistent DBs.

An unsatisfiable class is simply a class that cannot have any instances. Say, for example, that we added the following axioms to MyDB₂:

stating that companies cannot be organizations and vice versa, and that an LLC is a company and an organization. The disjointness axiom causes the class :LLC to be unsatisfiable because, for the DB to be free of any logical contradiction, there can be no instances of :LLC.

Asserting (or inferring) that an unsatisfiable class has an instance, causes the DB to be inconsistent. In the particular case of MyDB₂, we know that :clark_and_parsia is a company and an organization; therefore, we also know that it is an instance of :LLC, and as :LLC is known to be unsatisfiable, we have that MyDB₂ is inconsistent.

Using reasoning in order to discover modeling errors in the context of an enterprise application is useful in order to maintain a correct contradiction-free model of the domain. In our example, we discovered that :LLC is unsatisfiable and MyDB₂ is inconsistent, which leads us to believe that there is a modeling error in our DB. In this case, it is easy to see that the problem is the disjointness axiom between :Company and :Organization.

As explained in the OWL 2 Web Ontology Language Profiles Specification, an OWL 2 profile is a reduced version of OWL 2 that trades some expressive power for efficiency of reasoning. There are three OWL 2 profiles, each of which achieves efficiency differently.

Each profile restricts the kinds of axiom and assertion that can be used in a DB. Colloquially, QL is the least expressive of the profiles, followed by RL and EL; however, strictly speaking, no profile is more expressive than any other as they provide incomparable sets of constructs.

Stardog supports the three profiles of OWL 2. Notably, since TBox BGPs are handled completely by Pellet, Stardog supports reasoning for the whole of OWL 2 for queries containing TBox BGPs only.

This kind of constraint guarantees certain subclass and superclass (i.e., subsumption) relationships exist between instances.

These constraints control the types of domain and range instances of properties.